POST /v1/documents?uri={db-uri}

Summary

Perform a partial update to content or metadata of a document at a caller-specified URI. This operation is equivalent to PATCH /v1/documents.

Response

Upon success, MarkLogic Server responds with 201 (Document Created) or 204 (Updated or Unchanged).

Required Privileges

http://marklogic.com/xdmp/privileges/rest-writer

http://marklogic.com/xdmp/privileges/rest-reader

Usage Notes

Use this form of POST /v1/documents to update a portion of the content and/or metadata for an existing document at a caller-supplied URI. For all other document and metadata creation and update operations, use PUT /v1/documents or one of the other forms of POST /v1/documents.

You can also use a PATCH request to apply a partial update. For details, see PATCH /v1/documents. The functionality and request body contents are the same.

To perform a partial update of content and/or metadata, specify the document URI using the uri parameter, set the category parameter to reflect the content and/or metadata to be modified, and set the request header X-HTTP-Method-Override to PATCH. The request body must be a JSON or XML patch specification.

You can only apply partial updates of content to XML and JSON documents. You can apply partial updates of metadata to any document type.

When patching a temporal document, the uri parameter specifies the URI of the output document. If you do not specify a source document using source-document or temporal-document, then uri also specifies the URI of the input document.

Use the temporal-document parameter to identify the temporal document collection URI. If temporal-document is present and source-document is not present, then temporal-document identifies the input document. If source-document is present, then it identifies the input document. The input document must be in the temporal collection specified in the temporal-collection parameter.

The metadata-values category represents "metadata fields" document metadata. For more details, see Metadata Fields in the Administrator's Guide.

See Also

• Partially Updating Document Content or Metadata in the REST Application Developer's Guide.

Example

$ cat ./my-patch.xml
<rapi:patch xmlns:rapi="http://marklogic.com/rest-api" 
    xmlns:my-ns="http://marklogic.com/examples">
  <rapi:insert context="/my-ns:parent" position="last-child">
    <my-ns:child>inserted</my-ns:child>
  </rapi:insert>
</rapi:patch>

curl --anyauth --user user:password -X POST -d@'./my-patch.xml' -i \
  -H "Content-type: application/xml" -H "X-HTTP-Method-Override: PATCH" \
  'http://localhost:8000/v1/documents?uri=/doc/example.xml'

==> Perform a partial update on the document with URI /doc/example.xml.
    A <child/> element is added as the last child of the node with
    the XPath /my-ns:parent. MarkLogic Server responds with headers
    similar to the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
  

Example

$ cat ./my-patch.json
{ "patch": [
    { "insert": {
          "context": "/parent",
          "position": "last-child",
          "content": { "child": "inserted" }
    }}
] }

curl --anyauth --user user:password -X POST -d@'./my-patch.json' -i \
  -H "Content-type: application/json" -H "X-HTTP-Method-Override: PATCH" \
  'http://localhost:8000/v1/documents?uri=/doc/example.json'

==> Perform a partial update on the document with URI /doc/example.json.
    A key-value pair with key 'child' is added as the last child of the 
    top level 'parent' key.  MarkLogic Server responds with headers
    similar to the following:

Content-type: application/xml
Server: MarkLogic
Content-Length: 211
Connection: Keep-Alive
Keep-Alive: timeout=5

HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5